White Paper

from Pocket Soft

90 to 99% compression, in typical usage, saves money distributing fixes and updates. .RTPatch Professional works at the binary level with executables, data, text; any type of file. .RTPatch Professional consists of two steps:

1) Patch Build

2) Patch Apply

.RTPatch Build compares the old and new systems. A system can be one file or many files scattered throughout directories on your hard disk. Patch Build analyzes the two systems to decide what files have been modified, deleted, added, and renamed between the two systems. It then creates a patch file containing the changes needed to convert an old system to a new one. This patch file is automatically compressed to make it even smaller.

The second step is applying the patch file to an old system, such as one existing on an end-user's machine. You provide your end user with the patch application step, Patch Apply, and the patch file.

You can distribute patch files and the Patch Apply program on a floppy disk, on an electronic bulletin board, via modem, etc.

Extensive error checking is performed both at the time that patch file is constructed and when it is applied on the end-user's machine, ensuring the integrity of the updated system.

The patch application program can also create backup copies of the files affected by the patch so that you can reconstruct the original system, if needed.

.RTPatch professional is available for the following platforms:

OS/2®

UNIX®

Windows®

Windows NT®

Windows 95

DOS

Building a patch may be as simple as simply passing two directory names to PATCHBLD on the command line, a directory that contains your old system and one that contains your new system. For example:

PATCHBLD OLDSYS NEWSYS

If the directory OLDSYS contains subdirectories, simply append a /s (DOS) or a -s (UNIX) to the directory name; if the directory NEWSYS contains subdirectories, simply append a /f (DOS) or a -f (UNIX) to the directory name. Most users can build patches this simply.

To invoke some of the special features of PATCHBLD, such as handling serialized files, updating multiple systems with a single patch, and updating a variety of older versions to the current version with the same patch, you must use a command file. A command file also allows greater control over which files in a directory tree PATCHBLD should compare. A command file is simply an ASCII text file giving commands to PATCHBLD one per line.

You can control PATCH behavior through command file switches. For instance, if you want PATCH to continue applying patches after it fails to find a file which it intends to patch, you can put the IGNOREMISSING command in the PATCHBLD command file. PATCHBLD command file commands that affect the behavior of PATCH are also available as PATCH command line switches.

There are four actions that PATCHBLD may take with each particular file in a system. A patch file is actually a concatenation of individual patching actions for each file in a system. The four possible actions are:

1. MODIFY: PATCHBLD generates a MODIFY file patch when a file's name remains the same, but the contents have changed. This is the main type of patch; it is the one that allows you to send only the changes to binary and text files.

1. ADD: PATCHBLD generates an ADD patch if a file exists in the new system, but not in the old system. An added file will overwrite a file of the same name on the end-user's system. You can force an ADD patch by using the ADD command in the PATCHBLD command file. If you use the /f (DOS) or -f (UNIX) switch on the NEWDIR specification, PATCH adds a file to a directory with the same name on the end-user's system as the directory it came from on your system; PATCH will create this directory on the end-user's system if it does not exist.

1. DELETE: PATCHBLD generates a DELETE patch if a file exists in the old system, but not in the new system. You can force a particular file's deletion by using the DELETE command in the PATCHBLD command file.

1. RENAME: If a file's name has changed, but its contents are the same, you can use the RENAME command in the PATCHBLD command file to ensure that just an instruction to change the name will appear in the patch file, rather than a DELETE of the old file and an ADD of the new file.

PATCHBLD also outputs an ASCII text file with an .RTD extension, called the documentation file. This file lists each of the files affected by the patch, and which of the above four actions applies to each one.

There are several ways to apply the output of the PATCHBLD program, henceforth known as a patch file, to the original system of files. The easiest is to send the end-user the small command line executable PATCH, along with the patch file. You need only send PATCH the first time you send an update to an end-user. PATCH takes up to three optional parameters in any order:

PATCH [switches] [update directory] [patch file name]

The [switches] parameter takes any of the switches that toggle a PATCH feature. Switches toggle features such as the automatic backup of the old system prior to the patch application; the ability of PATCH to back out of changes already made to files in the event of error; whether or not PATCH searches on the path or in subdirectories for files to update; and whether PATCH will quit when it fails to find a file which it intends to update. Each of these attributes has a default which you may toggle either at build or apply time.

The [update directory] parameter specifies the directory on the end-user's system that contains the files to update. In the absence of this parameter, the update directory is the current directory. The update directory can have any name on the end-user's system, since PATCH searches for files to update, not specific directory names. PATCH will search for files to update in the update directory; in subdirectories of the update directory; or in directories listed on the PATH environment variable. You can cause PATCH not to search in either of the latter two places with the use of switches, described above.

Note that there are actually three systems involved in the building and applying of a patch: the old and new systems on your machine, and the end-user's system. The end-user's system need only be like the old system on your end in that it contains the same files. The directory structure in which these files reside on the end-user's system need not be identical to the directory structure on your machine.

The [patch file name] parameter gives the name of the patch file to apply. In the absence of this parameter, the default is "PATCH.RTP". You can name the patch file with the PATCHBLD -O:<name> command line option, or the PATCHBLD OUTPUT command file command.

Each attribute of PATCH behavior for which there is a switch has a default setting, and the switch can toggle the setting on or off in a PATCHBLD command file or on the PATCH command line. Thus, you can either define certain modes of PATCH behavior when you build the patch, or have your end-users choose the behavior when they apply the patch.

There are alternative methods of applying a patch file to shipping the command line executable PATCH and having your end-users run it. The memory usage of PATCH is small, and switches (-NOMESSAGE, -QUIET) are available to suppress all screen output of PATCH; thus, you can seamlessly spawn patch from your own installation program. Some supported platforms include the ability to program a graphical interface to the patch apply process, and also the ability to send a self-applying patch file.

The backup feature allows the automatic backup of all the old system files prior to the application of the patch. With this feature, PATCH copies the update directory, including all subdirectories, to a backup directory. PATCH writes a batch file that the end-user can run to restore the original system.

PATCH can back out of any changes made to the end-user's files on error or interruption of the apply process due to power outage, ctrl-c, or turning off the computer. By default, if PATCH encounters an error condition and stops, or if something interrupts PATCH, the files that PATCH has already updated will remain updated, and the file that PATCH has currently open will not be updated. However, if you enable the undo feature, the original system will be intact.

PATCH checks two things before it will apply a modify patch for a file. When PATCH finds a file of the appropriate name, it first compares the size of the file with the size of the original. If the file size is the same, it then calculates a checksum for the file, and compares it to a checksum calculated for the original file. If the file passes this test, it is definitely the same as the original, and PATCH applies the changes. If the file does not pass, then PATCH continues looking for a file of the same name, until it has exhausted all search possibilities. In this event, PATCH either quits with an error or continues with a warning, based on a parameter set at build or apply time.

You can password protect a patch file to ensure that only end-users authorized to apply the patch file can do so.

This feature allows the updating of a variety of different older versions to a single current version with one patch file. For example, history patching is useful if you do not know which end-users have which versions of a software system. Furthermore, history patching works on a file-by-file basis, so that an end-user might have files mixed from several different versions, and still apply one patch file to become current. History patching allows you to create a patch file that will update every end-user to the current version, regardless of which version or combination of versions with which they began.

PATCH syntax assumes that all files that require updating lie under one directory, called the update directory. However, this assumption may not suffice for certain software installation schemes. For instance, an installation program might install the main software files in one directory, and some supporting files in another directory on another drive. .RTPatch allows you to deal with such a complicated software installation.

Files may have unique serial numbers or certain regions configurable by the end-user that might contain a company name or other information. Such information that differs from file to file would ordinarily cause PATCH not to apply a patch (since the checksums for files with different serial numbers or data would not match). PATCHBLD allows you to deal with serial numbers or other regions in a file which may differ from user to user. You may have PATCH ignore or retain from the old to new version certain portions of a file, specified at build time by address and length. Furthermore, you may have PATCH insert a new serial number in a file.

You may include a temporary file in a patch file which PATCH uncompresses upon applying the patch file and deletes after the patching process completes. You may also run any command line during the patching process. These features allow for powerful customization of the patch applying process. PATCH can execute the temporary file using the execution hook, thus allowing custom file processing in the background while the updating continues. Furthermore, the execution hook allows custom patching not covered by the many other features of PATCH. For example, you could use this feature to create an empty subdirectory, something which PATCH could not ordinarily do.

.RTPatch provides utility programs that allow you to locate strings of ASCII characters or bytes in a file. These programs are useful in conjunction with the serial number features described above. .RTPatch also includes a utility that compares files and indicates whether the files are different and where they differ. .RTPatch provides utilities for splitting a patch file across diskettes, and putting thus split patch files back together.

Memory Needed at Build Time

1. When comparing two large files, PATCHBLD runs most efficiently if it has enough memory available to load both the old and new versions of the file into memory. Thus PATCHBLD will perform best if the amount of RAM on the system is at least (2 x (Size of Largest File in Systems Being Compared)) + 2Mb.

1. PATCHBLD still runs well if one of the files, old or new, fits completely into memory; however, when neither of the files being compared fits entirely into memory, PATCHBLD must do considerably more work when comparing the files. PATCHBLD will build patches for files which do not fit entirely in memory; however, a swapfile will be created on disk to hold overflow data, and build time may increase substantially.

1. You will typically not notice this problem with executable files, since an executable file will rarely be large enough to exceed our RAM requirements. However, the problem may become evident when building patches for very large data files. One of the focal points of current .RTPatch development is to allow .RTPatch to build patches for very large data files more quickly.

Building Patches for Compressed or Encrypted Files

PATCHBLD will build inefficient patch files for files that have been compressed with some utility (PKZIP, LHA, etc.). You might find that the patch file is larger than either of the original files. Encrypted files also may cause inefficient patch file sizes.

Pocket Soft, Inc.   			phone:	 (800)826-8086
PO Box 821049     				 (713)460-5600
Houston, TX 77282-1049    		fax:     (713)460-2651
USA      				URL:   http://www.pocketsoft.com
					Email:  info@pocketsoft.com